Skip to content

Comments

Implement wire protocol as wool-protocol namespace package#2

Merged
conradbzura merged 5 commits intomainfrom
1-extract-wire-protocol
Feb 24, 2026
Merged

Implement wire protocol as wool-protocol namespace package#2
conradbzura merged 5 commits intomainfrom
1-extract-wire-protocol

Conversation

@conradbzura
Copy link
Contributor

@conradbzura conradbzura commented Feb 23, 2026 •
edited
Loading

Summary

Implement Wool's wire protocol — protobuf schemas, generated Python bindings, and wrapper modules — as a namespace package importable as wool.protocol. Include protobuf definitions for task and worker messages, gRPC service wrappers, a service registry, and CI/CD workflows for testing, releasing, and repo hygiene.

Closes #1

Proposed changes

Add wool.protocol namespace package

Create protobuf schemas (task.proto, worker.proto) defining the gRPC Worker service, task dispatch messages (TaskEnvelope, Task, Ack, Nack, Result, Exception), and the response streaming protocol (Response). Add wrapper modules under src/wool/protocol/ providing a clean public API with error handling and a service registry. Configure pyproject.toml with package metadata, build hooks for git-based versioning and gRPC import fixup, and dependencies.

Add CI/CD workflows

Add 7 workflow files for test execution (pyright + pytest across Python 3.11–3.13), release cutting, publishing, PR validation, labeling, and branch sync. Include 6 composite actions and supporting shell scripts for versioning, publishing, and setup.

Add protobuf wrapper tests

Add tests for the wrapper modules (task.py, worker.py, exception.py, __init__.py) covering public API exports, error handling, and the service registry.

Test cases

Test Suite Test ID Given When Then Coverage Target
TestTaskModule TM-001 The task module Checking __all__ Contains exactly Ack, Exception, Nack, Result, Task, TaskEnvelope, Worker task.py __all__
TestTaskModule TM-002 The task module Accessing Task Is a protobuf Message subclass task.py public export
TestTaskModule TM-003 The task module Accessing Result Is a protobuf Message subclass task.py public export
TestTaskModule TM-004 The task module Accessing Exception Is a protobuf Message subclass task.py public export
TestTaskModule TM-005 The task module Accessing TaskEnvelope Is a protobuf Message subclass task.py public export
TestTaskModule TM-006 The task module Accessing Worker Is a protobuf Message subclass task.py public export
TestTaskModule TM-007 The task module Accessing Ack Is a protobuf Message with a version field task.py public export
TestTaskModule TM-008 The task module Accessing Nack Is a protobuf Message with a reason field task.py public export
TestWorkerModule WM-001 The worker module Checking __all__ Contains exactly 7 symbols: Response, StopRequest, Void, WorkerMetadata, WorkerServicer, WorkerStub, add_WorkerServicer_to_server worker.py __all__
TestWorkerModule WM-002 The worker module Accessing WorkerServicer Is a class with dispatch and stop methods worker.py public export
TestWorkerModule WM-003 The worker module Accessing WorkerStub Is a class worker.py public export
TestWorkerModule WM-004 The worker module Accessing Response Is a protobuf Message subclass worker.py public export
TestWorkerModule WM-005 The worker module Accessing WorkerMetadata Is a protobuf Message subclass worker.py public export
TestWorkerModule WM-006 The worker module Accessing add_WorkerServicer_to_server Is callable worker.py public export
TestProtobufImportError PE-001 An ImportError with message "No module named 'foo'" Wrapping in ProtobufImportError Includes original message and compilation hint exception.py
TestProtobufImportError PE-002 A ProtobufImportError instance Checking its type Is an ImportError subclass exception.py
TestServiceRegistry SR-001 The protocol package Accessing add_to_server Maps WorkerServicer to add_WorkerServicer_to_server __init__.py registry
TestServiceRegistry SR-002 The protocol package Checking add_to_server length Contains exactly 1 entry __init__.py registry

Implementation plan

    • Add protobuf schemas (task.proto, worker.proto) and configure pyproject.toml with package metadata, build hooks, and dependencies
    • Add wrapper modules (task.py, worker.py, exception.py, __init__.py) under src/wool/protocol/ with public API, error handling, and service registry
    • Add CI/CD workflow files, composite actions, and shell scripts
    • Add protobuf wrapper test suite (tests/protocol/) covering TM-001 through SR-002

@conradbzura conradbzura linked an issue Feb 23, 2026 that may be closed by this pull request
Implement wire protocol as wool-protocol namespace package #1
Closed
@conradbzura conradbzura changed the title Extract wire protocol into standalone wool-protocol package Extract wire protocol into standalone wool-protocol namespace package Feb 23, 2026
@conradbzura conradbzura force-pushed the 1-extract-wire-protocol branch from ec1d923 to 7406525 Compare February 23, 2026 15:06
@wool-labs wool-labs bot added the code-change Indicates that a PR should trigger a release label Feb 23, 2026
@conradbzura conradbzura force-pushed the 1-extract-wire-protocol branch from 7406525 to a2c07fc Compare February 23, 2026 15:08
@conradbzura conradbzura changed the title Extract wire protocol into standalone wool-protocol namespace package Add wire protocol as wool-protocol namespace package Feb 23, 2026
@conradbzura conradbzura force-pushed the 1-extract-wire-protocol branch from a2c07fc to f6b8a68 Compare February 23, 2026 15:31
@conradbzura conradbzura added documentation Indicates that a PR includes changes to documentation feature New feature or capability cicd CI/CD pipeline changes build Build system or dependency changes labels Feb 23, 2026
@conradbzura conradbzura changed the title Add wire protocol as wool-protocol namespace package Implement wire protocol as wool-protocol namespace package Feb 23, 2026
@conradbzura conradbzura force-pushed the 1-extract-wire-protocol branch 5 times, most recently from 436a6f9 to 30cc069 Compare February 23, 2026 16:51
@conradbzura conradbzura self-assigned this Feb 23, 2026
@conradbzura conradbzura force-pushed the 1-extract-wire-protocol branch 2 times, most recently from 7d19d4e to eee14cf Compare February 23, 2026 17:27
@conradbzura
build: Add repo scaffolding and build infrastructure
2785bb5 
Add .gitignore, LICENSE (Apache 2.0), and README for the
wool-protocol repository. Include build hooks for git-based
versioning and gRPC import fixup.
@conradbzura
ci: Add GitHub workflows, actions, and scripts
c637bcc 
Add CI/CD infrastructure for the wool-protocol repo: test
runner, release cutting, publishing, PR labeling and validation,
branch syncing, and issue templates.
@conradbzura conradbzura force-pushed the 1-extract-wire-protocol branch 2 times, most recently from 4c850a2 to 1592c64 Compare February 24, 2026 03:06
conradbzura
conradbzura commented Feb 24, 2026
View reviewed changes
conradbzura
conradbzura commented Feb 24, 2026
View reviewed changes
@conradbzura conradbzura marked this pull request as ready for review February 24, 2026 14:03
@conradbzura
feat: Implement wool.protocol namespace package
8f9a38e 
Implement Wool's wire protocol as a namespace package importable as
wool.protocol. Includes protobuf definitions for task and worker
messages, gRPC service wrappers, and the service registry.
@conradbzura
test: Add protocol wrapper tests
2500451 
Add 18 tests covering the wool.protocol public surface: task
module exports and protobuf messages, worker module exports
with servicer/stub/message verification, ProtobufImportError
wrapping, and the service registry mapping.
@conradbzura
docs: Add LLM guides and skill documents
cacb0d8
@conradbzura conradbzura force-pushed the 1-extract-wire-protocol branch from 1592c64 to cacb0d8 Compare February 24, 2026 15:15
@conradbzura conradbzura merged commit dab9d64 into main Feb 24, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@conradbzura conradbzura

Labels

build Build system or dependency changes cicd CI/CD pipeline changes code-change Indicates that a PR should trigger a release documentation Indicates that a PR includes changes to documentation feature New feature or capability

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Implement wire protocol as wool-protocol namespace package

1 participant

@conradbzura